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PATENT APPLICATION 

Invention Title: 

AN APPLICATION PROGRAMMING INTERFACE TO THE SIMPLE OBJECT 
ACCESS PROTOCOL 



Inventors: 

Sarita M. JAMES US Bellevue Washington 

INVENTOR'S NAME CITIZENSHIP CITY OF RESIDENCE STATE or FOREIGN COUNTRY 



Shyamalan PATHER South Africa Seattle Washington 

INVENTOR'S NAME CITIZENSHIP CITY OF RESIDENCE STATE or FOREIGN COUNTRY 



Be it known that the inventors listed above have invented a certain new and useful 
invention with the title shown above of which the following is a specification. 



TITLE 

An Application Programming Interface to the Simple Object Access Protocol 

TECHNICAL FIELD 

This invention relates generally to computer operating system services, and, more 
particularly, to an application programming interface to the Simple Object Access 
Protocol. 

BACKGROUND OF THE INVENTION 

SOAP ("Simple Object Access Protocol") is a standard method for a client 
application running on one computer to request services from a server application running 
on another computer. SOAP encodes remote procedure calls into XML messages that are 
carried to the server by an HTTP transport protocol. By standardizing the protocol for this 
much-used service, SOAP eliminates protocol development redundancy and application- 
specific protocol variations. SOAP has been proposed to the Internet Engineering Task 
Force for consideration as an Internet communications standard. The proposal may be 
found at http://search.ietf.org/mtemet-drafts/draft-box-http-soap-01.txt. 

However, the proposed SOAP standard does not specify an application 
programming interface (API) to allow applications to easily use SOAP. Each applications 
development group must individually code the interactions between its application and 
the SOAP protocol, leading to resource waste through coding replication and possibly to 
interoperability errors when connecting applications written by different development 
groups. Therefore, the lack of a standard SOAP API directly counters some of the 
benefits hoped to be achieved by using SOAP. 

SUMMARY OF THE INVENTION 

The above problems and shortcomings, and others, are addressed by the present 
invention, which can be understood by referring to the specification, drawings, and 
claims. The invention provides a general API for SOAP-using client applications. The 
API provides mechanisms for creating all parts of SOAP request messages, for sending 
the created messages over HTTP to a remote server, and, if the request is successful, for 
retrieving the response from the remote server, or, in the case of failure, for accessing 
whatever error information is available. Applications developers building on top of this 
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API are freed from redeveloping these general mechanisms and can thus focus on the 
unique aspects of their applications. 

In one embodiment of the present invention, the API consists of software objects. 
In addition to providing the well-known benefits of an object-oriented interface, this 
5 embodiment parameterizes the information passed through the API. Because of this, both 
the SOAP protocol and the applications that use it can change without requiring changes 
to the API. 

Besides the aspects, features, and advantages described, the invention includes 
other aspects, features, and advantages that will become apparent from studying the 
10 following detailed description and claims. 

BRIEF DESCRIPTION OF THE DRAWINGS 
While the appended claims set forth the features of the present invention with 
particularity, the invention, together with its objects and advantages, may be best 
understood from the following detailed description taken in conjunction with the 
1 5 accompanying drawings of which: 

Figure 1 is a block diagram generally illustrating an exemplary computer system 
which may support the present invention; and 

Figure 2 shows the steps an application may go through when using an object- 
oriented SOAP API according to one embodiment of the present invention. 
20 DETAILED DESCRIPTION OF THE INVENTION 

Turning to the drawings, wherein like reference numerals refer to like elements, 
the invention is illustrated as being implemented in a suitable computing environment. 
Although not required, the invention will be described in the general context of computer- 
executable instructions, such as program modules, being executed by a personal 
25 computer. Generally, program modules include routines, programs, objects, components, 
data structures, etc., that perform particular tasks or implement particular abstract data 
types. Moreover, those skilled in the art will appreciate that the invention may be 
practiced with other computer system configurations, including hand-held devices, multi- 
processor systems, microprocessor based or programmable consumer electronics, 
30 network PCs, minicomputers, mainframe computers, and the like. The invention may also 
be practiced in distributed computing environments where tasks are performed by remote 
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processing devices that are linked through a communications network. In a distributed 
computing environment, program modules may be located in both local and remote 
memory storage devices. 

Overview of a General-Purpose Computer 

5 With reference to Figure 1, an exemplary system for implementing the invention 

includes a general-purpose computing device in the form of a conventional personal 
computer 20, including a processing unit 21, a system memory 22, and a system bus 23 
that couples various system components, including the system memory, to the processing 
unit 21. The system bus 23 may be any of several types of bus structures including a 

1 0 memory bus or memory controller, a peripheral bus, and a local bus using any of a variety 
of bus architectures. The system memory includes read only memory (ROM) 24 and 
random access memory (RAM) 25. A basic input/output system (BIOS) 26, containing 
the basic routines that help to transfer information between elements within the personal 
computer 20, such as during start-up, is stored in ROM 24. The personal computer 20 

15 further includes a hard disk drive 27 for reading from and writing to a hard disk 60, a 
magnetic disk drive 28 for reading from or writing to a removable magnetic disk 29, and 
an optical disk drive 30 for reading from or writing to a removable optical disk 31 such as 
a CD ROM or other optical medium. 

The hard disk drive 27, magnetic disk drive 28, and optical disk drive 30 are 

20 connected to the system bus 23 by a hard disk drive interface 32, a magnetic disk drive 
interface 33, and an optical disk drive interface 34, respectively. The drives and their 
associated computer-readable media provide nonvolatile storage of computer-readable 
instructions, data structures, program modules, and other data for the personal computer 
20. Although the exemplary environment described herein employs a hard disk 60, a 

25 removable magnetic disk 29, and a removable optical disk 31, it will be appreciated by 
those skilled in the art that other types of computer-readable media which can store data 
accessible by a computer, such as magnetic cassettes, flash memory cards, digital video 
disks, Bernoulli cartridges, random access memories, read only memories, and the like, 
may also be used in the exemplary operating environment. 

30 A number of program modules may be stored on the hard disk 60, magnetic disk 

29, optical disk 31, ROM 24, or RAM 25, including an operating system 35, one or more 
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applications programs 36, other program modules 37, and program data 38. Often, the 
operating system 35 offers services to applications programs 36 by way of one or more 
APIs (not shown). Because the operating system 35 incorporates these services, 
developers of applications programs 36 need not redevelop code to use the services. 

5 Examples of APIs provided by operating systems such as Microsoft's "WINDOWS" are 
well-known in the art. 

A user may enter commands and information into the personal computer 20 
through input devices such as a keyboard 40 and a pointing device 42. Other input 
devices (not shown) may include a microphone, joystick, game pad, satellite dish, 

10 scanner, and the like. These and other input devices are often connected to the processing 
unit 21 through a serial port interface 46 that is coupled to the system bus, but may be 
connected by other interfaces, such as a parallel port, game port, or a Universal Serial Bus 
(USB). A monitor 47 or other type of display device is also connected to the system bus 
23 via an interface, such as a video adapter 48. In addition to the monitor, personal 

15 computers typically include other peripheral output devices (not shown), such as speakers 
and printers. 

The personal computer 20 may operate in a networked environment using logical 
connections to one or more remote computers, such as a remote computer 49. The remote 
computer 49 may be another personal computer, a server, a router, a network PC, a peer 

20 device, or other common network node, and typically includes many or all of the 
elements described above relative to the personal computer 20, although only a memory 
storage device 50 has been illustrated in Figure 1. The logical connections depicted in 
Figure 1 include a local area network (LAN) 51 and a wide area network (WAN) 52. 
Such networking environments are commonplace in offices, enterprise-wide computer 

25 networks, intranets, and the Internet. 

When used in a LAN networking environment, the personal computer 20 is 
connected to the LAN 51 through a network interface or adapter 53. When used in a 
WAN networking environment, the personal computer 20 typically includes a modem 54 
or other means for establishing communications over the WAN 52, The modem 54, 

30 which may be internal or external, is connected to the system bus 23 via the serial port 
interface 46. In a networked environment, program modules depicted relative to the 



5 



personal computer 20, or portions thereof, may be stored in the remote memory storage 
device. It will be appreciated that the network connections shown are exemplary and 
other means of establishing a communications link between the computers may be used. 
In the description that follows, the invention will be described with reference to 

5 acts and symbolic representations of operations that are performed by one or more 
computers, unless indicated otherwise. As such, it will be understood that such acts and 
operations, which are at times referred to as being computer-executed, include the 
manipulation by the processing unit of the computer of electrical signals representing data 
in a structured form. This manipulation transforms the data or maintains them at locations 

10 in the memory system of the computer, which reconfigures or otherwise alters the 
operation of the computer in a manner well understood by those skilled in the art. The 
data structures where data are maintained are physical locations of the memory that have 
particular properties defined by the format of the data. However, while the invention is 
being described in the foregoing context, it is not meant to be limiting as those of skill in 

15 the art will appreciate that various of the acts and operations described hereinafter may 
also be implemented in hardware. 

An Application's Use of an Object-Oriented SOAP API 
In accordance with one aspect of the present invention, Figure 2 shows the steps 
an application may go through when using an object-oriented SOAP API. The client-side 

20 application 36, shown running on a general-purpose computer 20, needs a service 
provided by the server application 200. To request the service, the client-side application 
first creates a SOAP Request Object in step 202. This object conveniently presents to the 
client-side application all the information it needs with respect to this one SOAP request. 
In steps 204-208, the client-side application 36 opens the SOAP Request Object 

25 and writes into it the information needed to create the request message. This information 
includes the address of the server that will process the request and the request itself. 
According to one aspect of the invention, this information (and the response and status 
information described below) is passed via parameters: this allows both the client-side 
application and the SOAP protocol itself to change without requiring changes to the API. 

30 When all the information has been presented, the client-side application in step 210 tells 
the SOAP Request Object to format and send the request. 
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The SOAP Request message 212 is sent via the HTTP protocol to the remote 

server 49, shown here connected to the client-side application's host by a LAN 51. The 

connection between these two machines may be much more elaborate, involving dial-up 

modems, the Internet, and the like. The SOAP Request message is passed along to the 

5 server application 200. Ideally, the server application responds favorably to the request, 

performs the requested service, and sends back a SOAP Response message 214. 

The SOAP API provides one place for retrieving all status and response 

information relevant to this one SOAP request. In step 216, the client-side application 36 

queries the SOAP Request Object. If the request was successfully processed, this Object 

10 includes an indication of success along with whatever information the server application 

200 passed along. Errors can occur anywhere in the communications system, from the 

client-side application's mistaken use of the SOAP API, to lack of resources (such as 

memory) on the client-side application's host machine 20, to congestion on the 

communications link 51, to unavailability of the remote server 49. Because of this, in the 

15 case of an error the SOAP Request Object includes not just a failure indication but as 

much error-resolution information as can be reasonably gathered. 

In order to prevent the client-side application 36 from having to constantly poll 

the SOAP Request Object for response and status information, the client-side application 

may be suspended in step 210 when the SOAP request is sent. The client-side application 

20 is then reanimated when there is new response or status information for it to process. 

A Detailed Usage Guide to an Object-Oriented SOAP API 

The steps 202-210, and 216 of Figure 2 are now described in more detail. A 

COM-based embodiment of the present invention may be built around an object class 

called SOAPRequest which exports the interface ISOAPRequest In the following, 

25 coding examples are given in JScript. 

Step 202 Create a SOAP Request Object 

A SOAP Request Object can be created using COM's standard object creation 

techniques. The following code creates the object, referring to the SOAPRequest class by 

the ProgID "SOAPAPI.SOAPRequest." 

30 //Create a SOAPRequest Object 

var soapRequest; 

soapRequest = new ActiveXObject("SOAPAPI.SOAPRequest"); 
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Step 204 Initialize the SOAP Request Object 

A SOAP Request Object is initialized with information about the remote service 

being requested. The client-side application 36 provides the name of the procedure that 

will perform the remote service and, optionally, the name of the interface to which the 

5 procedure belongs. The following code passes the name of the interface as a URI 

(Universal Resource Identifier); this is optional and the interpretation of its value is left 

up to the remote server 49. The procedure name is simply a text string; here it is 

"LoadFile". 

//Initialize the SOAPRequest Object 
10 soapRequest.Open("LoadFile", "MediaPlayer", "uuid:47edc63b-4a80-494a- 

beea-39122c4al20c"); 

Ste p 206 Initialize the Headers of the SOAP Request Object 

A client-side application 36 may wish to pass information to the remote server 

application 200 in addition to the information that is strictly part of the request for 

15 service. SOAP provides headers for this purpose, each header providing one piece of 
information for the server application. These headers and their attributes, including their 
number, names, and values, are not part of the SOAP specification but are defined by the 
client-side application. One embodiment of the invention parameterizes all of this 
information, thus allowing the information to change without requiring changes to the 

20 API. The information passing through the API in steps 208 and 216 is parameterized for 
similar reasons. 

Each SOAP header is an arbitrary XML fragment containing a single root 

element. The root element may contain child elements or text. This is an example of a 

SOAP header called sequenceNumber: 

25 <sequenceNumber> 
5 

</ sequenceNumber> 

Client-side applications 36 create header elements using XML DOM and then add 
them to a SOAP Request Object by calling the SetHeaderO method. For more 
30 information on XML DOM, see Microsoft's XML Developer's Guide, incorporated 
herein in its entirety by reference. The following three code segments show the creation 
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and setting of a header. First, create a new XML DOM Document Object that will be 

used in creating the subsequent XML Nodes to represent each header: 

//Create an XML DOM Document Object 
var xmlDoc; 

5 xmlDoc = new ActiveXObject("Microsoft.XMLDOM"); 

Next, use the XML DOM Document Object to create a sequenceNumber element and 
append to it a text node: 

//Create the sequenceNumber Node 

var sequenceNumberNode; 
1 0 sequenceNumberNode = xmlDocxreateElement("sequenceNumber"); 

//Create the Text for the sequenceNumber and Attach It 

var sequenceNumberTextNode; 

sequenceNumberTextNode = xmlDoc.createTextNode("5"); 
sequenceNumberNode.appendChild(sequenceNumberTextNode); 

15 Once the header element is created, it is added to the SOAP Request Object by calling 

SetHeaderO- SetHeaderO may also be used to change the value of an existing header. 

//Add the sequenceNumber as a Header 

soapRequest.SetHeader("sequenceNumber", sequenceNumberNode, 1); 

Because headers are defined by the client-side application 36 and not by the 

20 SOAP specification, it is quite possible that the remote server application 200 will receive 

a header that it does not understand. According to the SOAP specification, a header 

contains a mustUnderstand attribute. If this attribute is set to 1, then the server application 

cannot process the request unless it understands this header. SetHeaderO's third argument 

is the value of mustUnderstand. 
25 An application can delete a header element by calling DeleteHeaderO and can 

read the value of a parameter by querying the HeaderValue property. 

Step 208 Initialize the Parameters of the SOAP Request Object 

Requests can take any number of parameters of arbitrarily complex data types. 

Like the header elements described in the previous section, parameter values are 
30 expressed as XML fragments. Each parameter element consists of a root element that 

may contain either child elements or text. This XML fragment shows how a parameter 

named fileName is specified in a SOAP request: 

<filename> 

\\host\public\somefile.doc 
35 </filename> 
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An application uses the XML DOM to create a parameter element such as the one 

shown above, and then calls SetParameterO to add it to the SOAP Request Object. 

SetParameterO can also be used to change the value of an existing parameter. The 

following code creates a parameter element and inserts it into a SOAP Request Object: 

5 //Create the fileName Parameter Node 

var fileNameNode; 

fileNameNode = xmlDoc.createElement("fileName"); 
//Create the Node Containing the File Name Text and Attach It 

var fileNameTextNode; 
1 0 fileNameTextNode = xmlDoc.createTextNode( u \\host\public\somefile.doc"); 

fileNameNode.appendChild(fileNameTextNode); 
//Add the File Name as a Parameter 

soapRequest.SetParameter("fileName", fileNameNode); 

An application can delete a parameter element by calling DeleteParameterO and can read 
15 the value of a parameter by querying the ParameterValue property. 
Step 210 Send the SOAP Request to the Remote Server 

Once the headers and parameters are initialized, the client-side application 36 
calls the ExecuteO method to send the SOAP request to the remote server 49. The client- 
side application is suspended until the remote server sends a response, an error occurs, or 
20 thirty seconds pass without either of the above happening. In the case of a timeout, the 
client application resumes and ExecuteO returns a timeout error. In the other cases, 
Execute() returns and response and status information is available in the SOAP Request 
Object. The next section describes the information that may be returned. The following 
code sends a SOAP request to a server whose address is expressed as a URL (Uniform 
25 Resource Locator). 

//Execute the SOAP Request 

soapRequest.Execute("http://some_servercontrol/isapictldll?app"); 
Step 216 Determine the Result of the SOAP Request 

When the ExecuteO method returns, it passes a success or failure code to the 
30 client-side application 36. That application may then query various ISOAPRequest 
properties to read the values returned from the server application 200 (in the case of a 
successful request) and to access status information. 

If ExecuteO returns a success code, then the ResponseElement property contains 
the contents of the Body element of the XML response sent by the server application 200. 
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The contents of this property are server-dependent and the client-side application 36 
should know in advance what to expect. If the SOAP request defines any out parameters 
(parameters whose values might be changed by the server application), then the client- 
side application may query their new values by using the ParameterValue property. The 
5 ResponseHeaders property returns the contents of the headers sent by the server 
application 200. Just as a client-side application 36 can send additional information about 
a request in the SOAP headers, the server application can return additional information in 
the headers. 

When the request fails at the server application 200, the ResponseFaultCode, 
10 ResponseFaultString, and ResponseFaultDetail properties are filled from the contents of 
the server application's error response. 

The status of the network protocol is available in the ResponseHTTPStatus 
(HTTP status code) and ResponseHTTPStatusText (text description of the HTTP status 
code) properties. The values of these properties are, however, only interesting if there was 
15 a network-related failure. 

A Detailed Definition of an Object-Oriented SOAP API 
In accordance with one aspect of the present invention, the following is a 
complete definition of the object-oriented SOAP API used to illustrate the examples 
given above. 
20 [ 

object, 

uuid(EF 9A C5 05 - 0B 08 - 4F DD - 97 3C - 6B FD C9 A5 AD CA), 
helpstring("ISOAPRequest"), 
pointer_default(umque), 
25 nonextensible 

] 

interface ISOAPRequest: IDispatch 
{ 

//Initialization 
30 [id(0), helpstring("method Open")] 

HRESULT Open( [in]BSTR bstrMethodName, [inJBSTR bstrlhterfaceName, 
[in]BSTR bstrMethodNameSpace); 

//Header Manipulation 

[id(2), helpstring("method SetHeader")] 
35 HRESULT SetHeader( [in]BSTR bstrName, [in]IUnknown *pUnkNewValue, 

[in]VARIANT_BOOL vbMustUnderstand); 
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[id(3), helpstring("method DeleteHeader")] 
HRESULT DeleteHeader([in]BSTR bstrName); 

[propget, id(4), helpstring("property HeaderValue")] 
HRESULT HeaderValue( [in]BSTR bstrName, 

[out, retval]IUnknown **ppUnkValue); 

[propget, id(5), helpstring("method HeaderMustUnderstand")] 
HRESULT HeaderMustUnderstand([in]BSTR bstrName, 

[out, retval]VARIANT_BOOL 
*pvbMustUnderstand); 

//Parameter Manipulation 

[id(7), helpstring("method SetParameter")] 

HRESULT SetParameter([in]BSTR bstrName, [in]IUnknown *pUnkNew" 

[id(8), helpstring("method DeleteParameter")] 
HRESULT DeleteParameter([in]BSTR bstrName); 

[propget, id(9), helpstring("property ParameterValue")] 
HRESULT ParameterValue( [in]BSTR bstrName, 

[out, retval]IUnknown **ppUnkValue); 

//Invoke 

[id(10), helpstring("method Execute")] 
HRESULT Execute([in]BSTRbstrTargetURI); 

//Feedback 

[propget, id(l 1), helpstring('*property ResponseElement")] 
HRESULT ResponseElement([out, retval]RJnknown **ppUnkValue); 

[propget, id(12), helpstring("property ResponseHeaders")] 
HRESULT ResponseHeaders([out, retval]IUnknown **ppUnkValue); 

[propget, id(13), helpstring("property ResponseFaultCode")] 
HRESULT ResponseFaultCode([out, retval]BSTR *pbstrValue); 

[propget, id(14), helpstring("property ResponseFaultString")] 
HRESULT ResponseFaultString([out, retval]BSTR *pbstrValue); 

[propget, id(15), helpstring("property ResponseFaultDetail")] 
HRESULT ResponseFaultDetail([out, retval]nJnknown **ppUnkValue); 

[propget, id(16), helpstring("property ResponseHTTPStatus")] 
HRESULT ResponseHTTPStatus([out, retval]long *plValue); 

[propget, id(17), helpstring("property ResponseHTTPStatusText")] 
HRESULT ResponseHTTPStatusText([out, retval]BSTR *pbstrValue); 
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//For Debugging 

[propget, id(18), helpstring("property RequestXMLText")] 
HRESULT RequestXMLText([out, retval]BSTR *pbstrXMLText); 

}; 

5 Conclusion 

All of the references cited herein, including patents, patent applications, and 
publications, are hereby incorporated in their entireties by reference. 

In view of the many possible embodiments to which the principles of this 
invention may be applied, it should be recognized that the embodiments described herein 
10 with respect to the drawing figures are meant to be illustrative only and should not be 
taken as limiting the scope of invention. Therefore, the invention as described herein 
contemplates all such embodiments as may come within the scope of the following 
claims and equivalents thereof. 
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CLAIMS 

claim: 

A method for an application to communicate with a procedure on a remote server 
via the Simple Object Access Protocol (SOAP) comprising the steps of: 

issuing, by the application, a call to initialize a SOAP request, said 

initialization including specifying the procedure on the remote 

server; 

issuing, by the application, a call to set the body of the SOAP request, 

using a set of parameters to specify said body; 
issuing, by the application, a call to request that the SOAP request be sent 

to the remote server; 
issuing, by the application, a call to query the SOAP request to obtain 

status information; and 
issuing, by the application, a call to query the SOAP request to obtain 

response information sent from the procedure on the remote server. 

The method of claim 1 further comprising the step of: 

issuing, by the application, a call to set a header in the SOAP request, 

including in said header a value for the mustUnderstand attribute; 

The method of claim 1 wherein the call to request that the SOAP request be sent 
to the remote server does not return until either response information is received 
from the remote server or a set amount of time passes. 

The method of claim 1 wherein the SOAP request is a software object and the 
issued calls are to methods of the SOAP request software object. 



The method of claim 4 further comprising the step of: 

issuing, by the application, a call to instantiate the SOAP request software 
object. 
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A computer-readable medium containing instructions that when executed cause a 
computer to communicate with a procedure on a remote server by performing the 
steps of: 

initializing a SOAP request, said initialization including specifying the 

procedure on the remote server; 
setting the body of the SOAP request, using a set of parameters to specify 

said body; 

sending the SOAP request to the remote server; and 

querying the SOAP request to obtain status and response information. 

A system for using SOAP to communicate with a server application on a remote 
host comprising: 

a local host; 

a client application running on the local host; 

a communications link connecting the local host with the remote host; and 
a set of functions running on the local host callable by the client 

application to specify a SOAP request, to send the SOAP request 
to the remote host via the communications link, and to obtain 
status and response information concerning the SOAP request. 

The system of claim 7 wherein the set of functions is an application programming 
interface (API). 

The system of claim 8 wherein information passed through the API is in the form 
ofparameters. 

The system of claim 8 wherein the API consists essentially of software objects. 
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An API presented by an operating system comprising a software object into which 
the fields of a SOAP request can be written and which supports methods for 
requesting that the SOAP request be sent to a remote server, for retrieving 
response information sent from the remote server, and for retrieving status 
information about the SOAP request. 



A computer-readable medium containing instructions that when executed cause an 
operating system to present an API comprising a software object into which the 
fields of a SOAP request can be written and which supports methods for 
requesting that the SOAP request be sent to a remote server, for retrieving 
response information sent from the remote server, and for retrieving status 
information about the SOAP request. 
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ABSTRACT OF THE INVENTION 

Methods and systems for providing an application programming interface (API) 
to the Simple Object Access Protocol (SOAP) are described. The API provides 
mechanisms for creating all parts of SOAP request messages, for sending the created 
messages over HTTP to a remote server, and, if the request is successful, for retrieving 
the response from the remote server, or, in the case of failure, for accessing whatever 
error information is available. The information passed through the API can be in the form 
of parameters which allows both the SOAP protocol and the applications that use it to 
change without requiring changes to the API itself. 
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